Display a map

The smallest useful embed: one call mounts the map, and ready resolves with the capability descriptor - the commands and events this particular map will answer. Everything in the other examples builds on the handle embed() returns.

Open this example on its own

What to notice

  • embed(element, { publishId }) creates the frame and opens the control session.
  • map.ready resolves with { commands, events, policy, map }. Branch on commands, never on version numbers.
  • If your site is not on the map's allowed origins, ready rejects with denied_origin - the map still displays, it just cannot be driven.

The code

The complete page. Swap in your own publish id, and ask the map's author to add your site to its allowed origins.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Display a map - Icon Map Embed API</title>
  <link rel="stylesheet" href="https://www.icon-map.com/embed-examples/examples.css"> <!-- demo styling only -->
</head>
<body>
  <div class="ex-bar">
    <span class="ex-label">Status</span> <span id="status">connecting...</span>
    <span class="ex-spacer"></span>
    <span class="ex-label" id="details"></span>
  </div>
  <div class="ex-main"><div id="map"></div></div>

  <script src="https://www.icon-map.com/js/iconmap-embed/2/iconmap-embed.umd.min.js"></script>
  <script>
    const el = document.getElementById("map");

    // One call mounts the map. Everything else in these examples builds on the handle it returns.
    const map = IconMapEmbed.embed(el, {
      publishId: "pub_...",
      // The map is a globe: let this page's own background show in the space around it.
      background: "transparent",
      title: "World cities",
    });

    // `ready` resolves with what THIS map will answer: the commands, the events,
    // the author's switches and a few facts about the map.
    map.ready
      .then((capabilities) => {
        document.getElementById("status").textContent = "connected";
        document.getElementById("details").textContent =
          `${capabilities.commands.length} commands - ${capabilities.events.length} events - ` +
          `data: ${capabilities.map.dataMode} - languages: ${capabilities.map.locales.length}`;
      })
      .catch((error) => console.error(error.code, error.message));
  </script>
</body>
</html>

Read more